home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Experimental BBS Explossion 3
/
Experimental BBS Explossion III.iso
/
c
/
strpchrt.zip
/
USER.DOC
< prev
Wrap
Text File
|
1993-08-03
|
84KB
|
2,665 lines
PRINTING NOTES:
This file is an ASCII text file of the Strip Chart Library user
manual. It is about 45 pages long.
Use a non-proportional font (example: Courier) and a font size of
12 points for best printing results.
If you are importing this file to a word processor such as
WordPerfect, set the word processor's top, bottom, left and right
margins to zero.
STRIP CHART LIBRARY
USER'S MANUAL
Shareware Version 1.00
July, 1993
Copyright (c) 1993
Christopher Lim
517 Cobb Court
La Puente, California 91746
COPYRIGHT INFORMATION
Copyright (c) 1993 by Christopher S. Lim. All rights reserved.
This is a shareware program. Please refer to the READ.ME file
for registration, licensing and distribution information.
The author makes no warranty of any kind with regard to the
program or documentation, including, but not limited to, the
implied warranties of merchantability and fitness for a
particular purpose. The author shall not be liable in any event
for incidental or consequential damages in connection with, or
arising out of, the furnishing, performance, or use of the
program.
TRADEMARKS
Borland is a registered trademark of Borland International.
Epson LQ and Epson FX are registered trademarks of Seiko Epson
Corporation.
IBM is a registered trademark of International Business Machines.
Microsoft is a registered trademark of Microsoft Corporation.
TABLE OF CONTENTS
=================
Chapter 1 Getting Started . . . . . . . . . . . . . . . . . . 1
Chapter 2 Using the Strip Chart Library . . . . . . . . . . . 3
Chapter 3 Library Reference . . . . . . . . . . . . . . . . . 8
Chapter 4 Error Messages. . . . . . . . . . . . . . . . . . . 42
C H A P T E R 1
Getting Started
INTRODUCTION
============================================================
*** NOTE: Please read the READ.ME file before doing anything
else.
The Strip Chart Library is a C printer graphics library for
plotting strip charts on inexpensive dot matrix printers. A
strip chart is a continuous two-dimensional graph which
plots one or more traces (waveforms) versus time. The Strip
Chart Library contains functions that mimic and even exceed
the most useful features of very costly strip chart
recorders:
- Traces can be sized and placed anywhere on the chart.
- Traces may overlay or overlap other traces.
- Text and comments can be positioned anywhere on the
chart.
- Reference time axes can be positioned anywhere on the
chart.
- Events (high-low signals), with different marker types,
are supported.
- Waveform grid display, clipping and axis labeling are
supported.
- The number of channels is limited only by amount of
memory.
- Virtually any "plotting speed" may be simulated when
playing back previously acquired data.
SYSTEM REQUIREMENTS
============================================================
Computer Hardware and Software
------------------------------
The Strip Chart Library was designed and tested for IBM PC
compatible computers running the DOS operating system. A 25
Mhz 80386 or faster PC is highly recommended.
1
Supported Compilers
-------------------
The libraries were compiled with the following compilers:
SCBCS.LIB Borland C/C++ Version 3.1 (Small Memory
Model)
SCMSS.LIB Microsoft C/C++ Version 7.0 (Small Memory
Model)
If you use a different compiler or need a different memory
model, you will have to recompile the library source code.
Library source code is available to registered users. Please
refer to the READ.ME file for registration information.
Supported Printers
------------------
The Strip Chart Library supports the following tractor feed
dot-matrix printers:
Epson FX (9-pin) or compatible dot matrix printers
Epson LQ (24-pin) or compatible dot matrix printers
Both the narrow and wide carriage versions of the above
printers are supported. Color printers are currently not
supported. To improve performance, a large printer buffer
is recommended.
PRINTER SETUP
============================================================
The printer must be set up as follows:
Printer Mode: EPSON COMPATIBLE
Auto Line Feed: OFF
Paper Feed Type: TRACTOR FEED
Paper-Out Sensor: ON
Print Direction For Graphics (24 pin only): UNIDIRECT
Skip Over Perforation: OFF
NOTE: Most of the above functions are normally set through
the printer dip switch settings; consult your printer manual
on how to do this. You may need to experiment with the
other dip switches and user-settable functions of the
printer to get the best output. Run the sample test
programs to the check the quality of printer output.
2
C H A P T E R 2
Using the Strip Chart Library
OVERVIEW
============================================================
This section presents a brief summary of the functions
available in the Strip Chart Library. For more detailed
information about these functions, consult Chapter 3,
Library Reference.
The Strip Chart Library uses an objected-oriented approach
for creating and plotting strip charts: you control the
appearance of the strip chart by adding windows to the
paper and display data by adding the desired data values to
each window. The library takes care of the details of
plotting the data.
Writing a program with the Strip Chart Library consists of
five steps: Planning the Strip Chart, Initializing the
Strip Chart, Adding Windows to the Strip Chart, Adding Data
to the Windows, Terminating the Strip Chart. The following
sections cover these steps in more detail.
Include File
------------
Only one include file, SC.H, is required for every C source
file that calls a function from the Strip Chart Library.
Error Handling
--------------
Error conditions in the Strip Chart Library are handled in
two ways: (1) through calling an error trap function
defined by SC_SetErrorTrap, and (2) through returning a non-
zero error code (a zero value indicates no error) by most
functions in the Strip Chart Library. Using SC_SetErrorTrap
is the easier and preferred method; however, the error
return code is useful for pinpointing which portion of your
code committed the error. The nature of the error can be
examined by calling function SC_ErrorMsg. If an error
condition occurs, it is strongly suggested that you
immediately terminate or reinitialize the Strip Chart
Library as unpredictable results could occur if you continue
with the program.
3
PLANNING THE STRIP CHART
============================================================
Windows and Page Layout
-----------------------
Carefully plan the layout of the strip chart. Divide the
strip chart into windows. A window is a rectangular area on
the strip chart of fixed height and potentially infinite
length. There are five types of windows:
"Event Windows" accept and display event (two-state or
high-low) signal levels.
"Text Windows" accept and display messages.
"Time Windows" display reference time axes.
"Title Windows" accept and display a fixed string at
specified intervals.
"Trace Windows" accept and plot waveforms.
Units of Measure
----------------
Decide whether you want to use either English units (in
inches) or Metric units (in centimeters) to describe plot
length dimensions such as character height, window height
and window offset. You specify the type of unit to use in
function SC_Init.
Decide on the basic time unit you will use. For most cases,
you will probably be using seconds as the basic time unit.
However you may choose any other measurement of time such as
minutes, hours, or even weeks or months. To keep
terminology simple in this manual, we will assume that you
will be using seconds as the basic time unit.
Trace data are specified in real world coordinates (for
example, in volts). When you create a Trace Window, you
specify the maximum and minimum amplitudes in real world
coordinates that correspond to the top and bottom of the Trace
Window. See the descriptions for function SC_AddTraceWindow
and SC_Trace in Chapter 3 for more information.
Plot Speed
----------
Plot speed does not refer to the actual speed of paper or
chart movement but to the relationship of the chart's
horizontal dimension to the basic time unit. For example,
if you select a plot speed of 2 inches per second, two
inches measured along the horizontal (long side) of the
4
chart is equivalent to 1 second of time. You specify the
plot speed in function SC_Init.
INITIALIZING THE STRIP CHART LIBRARY
============================================================
Here is a summary of the functions used to initialize the
Strip Chart Library:
SC_Init Initializes the Strip Chart Library
and the printer. Except for
functions SC_SetErrorTrap and
SC_PrinterReady, SC_Init must be
called prior to any other function in
the Strip Chart Library.
SC_SetErrorTrap Specifies a function to trap errors.
SC_PrinterReady Checks if the printer is on-line and
ready to receive data.
ADDING WINDOWS TO THE STRIP CHART
============================================================
After initialization, the next step is to add windows to the
strip chart. Adding windows consists of calling a
SC_Add???Window function with the window position (yoffset),
window height (yheight), and other window-specific control
flags as arguments. Windows may be positioned anywhere
within the physical dimension of the paper; it is
permissible to have overlapping windows. The number of
windows that may be added is limited only by available
memory on your computer. The SC_Add???Window function, on
success, returns a pointer (SC_WINDOW *) that is used to
identify the window in subsequent operations. Below is the
summary of the functions to add windows:
SC_AddEventWindow Adds an Event Window to the strip
chart.
SC_AddTextWindow Adds a Text Window to the strip
chart. The height of the window
determines the character height.
SC_AddTimeWindow Adds a Time Window to the strip
chart. Time Windows consist of two
subwindows of equal height: one
subwindow contains the horizontal
axis and time tick marks, and a
second subwindow to display text
5
labels.
SC_AddTitleWindow Adds a Title Window to the strip
chart. Character height is equal to
the window height.
SC_AddTraceWindow Adds a Trace Window to the strip
chart.
Controlling the Appearance of Trace Windows
-------------------------------------------
The following functions control the appearance of Trace
Windows:
SC_SetHorizontalGrids Controls the number of horizontal
grids in Trace Windows.
SC_SetTimeGrids Controls the frequency of timing
grids in Trace Windows.
SC_SetYlabels Controls the appearance of vertical
axis labels in Trace Windows.
The above functions only affect Trace Windows added later.
Trace Windows that were created before calling any of the
above functions are not affected.
ADDING DATA TO STRIP CHART WINDOWS
============================================================
After the Strip Chart Library has been initialized and
windows added to the strip chart, data can now be displayed
in the windows. The following functions are used to add and
display data in the windows:
SC_Event Sets the event level (0 or 1) in an Event
Window.
SC_Text Adds a character string to a Text Window.
SC_Title Sets the title message in a Title Window.
SC_Trace Sets the trace amplitude in a Trace
Window.
SC_Draw Plots the contents of all windows up to
the current time position to an internal
printer buffer. SC_Draw should only be
called after all windows are updated to
the current time position.
6
SC_Advance Advances the paper to the next time
position.
Functions SC_Event, SC_Text, SC_Title and SC_Trace add data
to their respective windows at the current time position.
Calling SC_Draw is a signal to the Strip Chart Library that
you have finished adding data to all windows for the current
time position and the Library will proceed to plot the data.
The SC_Advance function moves the chart to the next time
position after which the Library is ready to accept more
data. It must be stressed that SC_Draw must be called
after data are added all windows and before calling
SC_Advance to advance the paper.
There are special cases where multiple calls to SC_Draw are
required before calling SC_Advance. One example involves
Trace Windows displaying step functions or square waves; see
the example in file EX_STEP.C.
TERMINATING THE STRIP CHART
============================================================
To terminate the strip chart, call function SC_Close:
SC_Close Closes the Strip Chart Library. All windows
are closed, the contents of internal buffers
are flushed, and memory allocated by the
Strip Chart Library are released.
7
C H A P T E R 3
Library Reference
SC_AddEventWindow
============================================================
Adds an Event Window to the strip chart.
SYNTAX
#include "sc.h"
SC_WINDOW *SC_AddEventWindow(double yoffset,
double yheight, int markerType, int fillType,
int *error);
RETURN VALUE
On success, SC_AddEventWindow returns a pointer to the
window. In the event of an error, it returns NULL.
REMARKS
yoffset [in] is the distance (in inches or centimeters)
from the top of the strip chart to the top of the Event
Window. yoffset must be greater than zero.
yheight [in] is the window height in inches or
centimeters.
markerType [in] is the type of event marker. An event
marker is used to display the state or level of a
binary (two-state or high-low) signal. Four types of
event markers are available:
SCM_PULSE--Event levels are displayed by high-low
pulses.
SCM_TICK--Event level changes are displayed by
vertical tick marks.
SCM_BAR--The high level is represented by bars.
SCM_BARLINE--Same as SCM_BAR except with a baseline
added.
fillType [in] specifies the fill type for SCM_BAR or
8
SCM_BARLINE event markers. Three fill types are
available:
NO_FILL--Bars are not shaded.
HALF_FILL--Bars are lightly shaded with dots.
SOLID_FILL--Bars are fully shaded.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_Event, SC_yoffset
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
SC_WINDOW *eventWindow;
/* Initialize: 8.5 inch wide paper, plot speed = 1
inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Event Window 0.5" from top of paper, 0.25 inch
window height, use pulse event markers
*/
eventWindow = SC_AddEventWindow(0.5, 0.25, SCM_PULSE,
NO_FILL, &error);
/* Draw events */
for (i=0; i < 10; i++) /* 10 second plot */
{
if ((i%2) == 0)
SC_Event(eventWindow, 0, &error); /* set event low
*/
else
SC_Event(eventWindow, 1, &error); /* set event high
*/
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
9
return 0;
}
SC_AddTextWindow
============================================================
Adds a Text Window to the strip chart.
SYNTAX
#include "sc.h"
SC_WINDOW *SC_AddTextWindow(double yoffset,
double yheight, int *error);
RETURN VALUE
On success, SC_AddTextWindow returns a pointer to the
window. In the event of an error, it returns NULL.
REMARKS
yoffset [in] is the distance (in inches or centimeters)
from the top of the strip chart to the top of the Text
Window. yoffset must be greater than zero.
yheight [in] is the window height in inches or
centimeters. The character height is equal to the
window height.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_Text, SC_yoffset
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
SC_WINDOW *textWindow;
10
/* Initialize: 8.5 inch wide paper, plot speed = 1
inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
if (error)
{
printf("%s\n",SC_ErrorMsg(error));
return 1; /* exit */
}
/* Add Text Window 1.5" from top of paper,
0.25" window height
*/
textWindow = SC_AddTextWindow(1.5, 0.25, &error);
/* Draw */
for (i=0; i < 10; i++) /* 10 second plot */
{
/* Display "hello world" every 2 seconds */
if ((i%2) == 0)
SC_Text(textWindow,"Hello World!",&error);
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
SC_AddTimeWindow
============================================================
Adds a Time Window to the strip chart.
SYNTAX
#include "sc.h"
SC_WINDOW *SC_AddTimeWindow(double yoffset,
double yheight, int type,
double tickInterval, int minorDiv,
char * (*userFunc)(SC_WINDOW *timeWindow,
double elapsedTime, unsigned long labelCount),
int *error);
RETURN VALUE
On success, SC_AddTimeWindow returns a pointer to the
window. In the event of an error, it returns null.
11
REMARKS
yoffset [in] is the distance (in inches or centimeters)
from the top of the strip chart to the top of the Time
Window. yoffset must be greater than zero.
yheight [in] is the window height in inches or
centimeters. The character height of the labels is
approximately one-half the window height. The height
of the major tick marks is approximately one-half the
window height.
type [in] specifies the type of the time window. There
are two types of time windows:
LABELS_BELOW_AXIS--Time labels are placed below the
time axis. Time tick marks are pointing upward.
LABELS_ABOVE_AXIS--Time labels are placed above the
time axis. Time tick marks are pointing downward.
tickInterval [in] specifies the time interval (in
seconds) between major tick marks.
minorDiv [in] specifies the number of minor divisions
between major tick marks.
userFunc [in] is a user-defined function to create the
string label to be placed at the major tick marks.
userFunc returns a pointer to the label string. At
every major tick interval, userFunc is called by the
library and passed the following arguments:
timeWindow--This is a pointer to the Time Window
where the label will be placed. If you have more
than one Time Window in your strip chart, you can
specify the same userFunc for each Time Window and
check the timeWindow argument to tell which Time
Window is about to be labeled.
elapsedTime--This is the elapsed time (in seconds)
from the start of the plot. The first major tick
mark always occurs at the very beginning of the plot
where userFunc is called with elapsedTime set to
0.0.
labelCount--This is the number of labels that has
been printed for this Time Window. The first major
tick mark always occurs at the very beginning of the
plot where userFunc is called with labelCount set to
0. The relationship between labelCount and
elapsedTime is:
12
elapsedTime = labelCount * tickInterval.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
char *LabelFunc(SC_WINDOW *w, double elapsedTime, unsigned
long labelCount)
{ /* user function to handle time axis labels */
static char buf[80]; /* string buffer must be declared as
static */
sprintf(buf,"%05.2f",elapsedTime); /* elapsedTime is in
seconds */
return buf;
}
int main(void)
{
int i;
int error;
SC_WINDOW *timeWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Time Window 1.0" from top of paper,
0.25" window height,
labels above time axis, label every 2 seconds,
5 divisions between labels.
*/
timeWindow = SC_AddTimeWindow(1.0, 0.25,
LABELS_ABOVE_AXIS, 2.0, 5, LabelFunc, &error);
/* Draw */
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
13
SC_AddTitleWindow
============================================================
Adds a Title Window to the strip chart.
SYNTAX
#include "sc.h"
SC_WINDOW *SC_AddTitleWindow(double yoffset,
double yheight, double interval, int *error);
RETURN VALUE
On success, SC_AddTitleWindow returns a pointer to the
window. In the event of an error, it returns null.
REMARKS
yoffset [in] is the distance (in inches or centimeters)
from the top of the strip chart to the top of the Title
Window. yoffset must be greater than zero.
yheight [in] is the window height in inches or
centimeters. The character height is equal to the
window height.
interval [in] is the time interval (in seconds) for
displaying the title string.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_Title, SC_yoffset
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
SC_WINDOW *titleWindow;
14
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Title Window 5.5" from top of paper,
0.25" window height,
display every 2.0 seconds
*/
titleWindow = SC_AddTitleWindow(5.5, 0.25, 2.0, &error);
/* Set title string. */
SC_Title(titleWindow, "Hello World!", &error);
/* Draw */
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
SC_AddTraceWindow
============================================================
Adds a Trace Window to the strip chart.
SYNTAX
#include "sc.h"
SC_WINDOW *SC_AddTraceWindow(double yoffset,
double yheight, double ymin, double ymax,
unsigned int flags, int *error);
RETURN VALUE
On success, SC_AddTraceWindow returns a pointer to the
window. In the event of an error, it returns null.
REMARKS
yoffset [in] is the distance (in inches or centimeters)
from the top of the strip chart to the top of the Trace
Window. yoffset must be greater than zero.
yheight [in] is the window height in inches or
centimeters.
15
ymin [in] is the real world Y coordinate corresponding
to the bottom border of the Trace Window.
ymax [in] is the real world Y coordinate corresponding
to the top border of the Trace Window. The values of
ymin and ymax may be changed dynamically at any time by
calling the SC_SetTraceRange function.
flags [in] are flags that control the appearance of
the trace window. Flags may be combined with the use
of the C bitwise OR ("|") operator.
SCF_NOFLAGS--Disables all flags.
SCF_BORDER--Adds a border around the window.
SCF_GRID--Adds horizontal and vertical grids.
Vertical (time) grid spacing are set through the
SC_SetTimeGrids function. Horizontal grid spacing
are set through the SC_SetHorizontalGrids function.
The SC_SetTimeGrids and SC_SetHorizontalGrids
functions must be called before calling
SC_AddTraceWindow.
SCF_YLABEL--Adds labels to the Y axis. The format
of the labels can be specified through the
SC_SetYlabels function. SC_SetYlabels must be
called prior to calling SC_AddTraceWindow.
SCF_CLIP--Segments outside the window are clipped.
If a segment is clipped, a thick solid line is drawn
at the top or bottom border where clipping occurs.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_SetHorizontalGrids, SC_SetTimeGrids, SC_SetTraceRange,
SC_SetYlabels, SC_Trace, SC_yoffset
16
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Set timing (vertical) grids to be 1 second apart. */
SC_SetTimeGrids(1.0, &error);
/* Set Y label format; display at 2.0 second intervals.
*/
SC_SetYlabels(10.0/72.0, "%+0.1f", 2.0, &error);
/* Divide trace into 4 equal sections. */
SC_SetHorizontalGrids(4, &error);
/* Add Trace Window 2.5" from top of paper,
1.0" window height,
amplitude range from -1.0 to 1.0, display borders,
display grids, label Y axis.
*/
traceWindow = SC_AddTraceWindow(2.5, 1.0,
-2.0, 2.0, SCF_BORDER | SCF_GRID | SCF_YLABEL,
&error);
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0;
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
17
SC_Advance
============================================================
Advances the paper.
SYNTAX
#include "sc.h"
void SC_Advance(double interval);
REMARKS
interval [in] is the time interval (in seconds) to
advance the paper. Function SC_Draw should normally be
called before calling SC_Advance.
SEE ALSO
SC_Draw
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Trace Window 2.5" from top of paper,
1.0" window height,
amplitude range from -1.0 to 1.0, display borders.
*/
traceWindow = SC_AddTraceWindow(2.5, 1.0,
-2.0, 2.0, SCF_BORDER, &error);
18
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0;
SC_Draw(); /* display y */
SC_Advance(1.0); /* advance to next position,
one second steps */
}
SC_Close();
return 0;
}
SC_Close
============================================================
Closes the Strip Chart Library.
SYNTAX
#include "sc.h"
void SC_Close(void);
REMARKS
SC_Close signals the end of the strip chart. The
contents of internal buffers are flushed, and memory
allocated by the Strip Chart Library are released.
SEE ALSO
SC_Init
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int error;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
19
/*
Program body
:
:
*/
SC_Close(); /* close the Strip Chart Library */
return 0;
}
SC_Draw
============================================================
Plots the contents of all windows up to the current time
position.
SYNTAX
#include "sc.h"
void SC_Draw(void);
REMARKS
SC_Draw plots the contents of all windows up to the
current time position to an internal printer buffer.
Actual printing is done only after this printer buffer is
filled. SC_Draw is normally called immediately before
the SC_Advance function to flush the window contents
before advancing the paper.
SEE ALSO
SC_Advance
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
20
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Trace Window 2.5" from top of paper,
1.0" window height,
amplitude range from -1.0 to 1.0, display borders.
*/
traceWindow = SC_AddTraceWindow(2.5, 1.0,
-2.0, 2.0, SCF_BORDER, &error);
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0;
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
SC_ErrorMsg
============================================================
Returns an error message string.
SYNTAX
#include "sc.h"
char *SC_ErrorMsg(int error);
RETURN VALUE
Pointer to an error message string.
REMARKS
error [in] is an error code number. A non-zero value
indicates an error occurred within the Strip Chart
Library. It is recommended that your program terminate
or reinitializes itself if an error is detected;
unpredictable results could occur if you continue with
the program.
21
SEE ALSO
SC_SetErrorTrap
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int error;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
if (error)
{
printf("%s\n", SC_ErrorMsg(error))
return 1; /* abort program */
}
/*
Program body
:
:
*/
SC_Close();
return 0;
}
22
SC_Event
============================================================
Sets the event level in an Event Window.
SYNTAX
#include "sc.h"
void SC_Event(SC_WINDOW *eventWindow, int eventlevel,
int *error);
REMARKS
eventWindow [in] is a pointer to the Event Window.
eventLevel [in] is the new level (0 = low, 1 = high) to
display.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
Gaps may appear in the plot if SC_Event is called twice
for the same Event Window without an intervening call to
SC_Draw.
SEE ALSO
SC_AddEventWindow
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
SC_WINDOW *eventWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Event Window 0.5 from top of paper,
0.25 inch window height,
use pulse event markers
*/
eventWindow = SC_AddEventWindow(0.5, 0.25, SCM_PULSE,
NO_FILL, &error);
23
/* Draw events */
for (i=0; i < 10; i++) /* 10 second plot */
{
if ((i%2) == 0)
SC_Event(eventWindow, 0, &error); /* set event low
*/
*/
else
SC_Event(eventWindow, 1, &error); /* set event high
*/
*/
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
SC_Init
============================================================
Initializes the Strip Chart Library.
SYNTAX
#include "sc.h"
void SC_Init(int port, unsigned char printerType,
unsigned char plotResolution, double units,
double paperWidth, double plotSpeed, int *error);
REMARKS
port [in] specifies the parallel port to which the
printer is attached, and is one of the following:
LPT1--parallel port 1.
LPT2--parallel port 2.
LPT3--parallel port 3.
printerType [in] specifies the type of printer. The
following printer types are currently recognized:
EPS_9PIN -- Specifies Epson compatible 9-pin dot
matrix printers.
EPS_24PIN -- Specifies Epson compatible 24-pin dot
matrix printers.
24
plotResolution [in] specifes the printer graphics mode
to be used and is one of the following:
LOW_RES -- Low resolution plots:
For 9 pin printers: 72 dpi (horizontally) by 60 dpi
(vertically). For 24 pin printers: 180 dpi
(horizontally) by 180 dpi (vertically).
HIGH_RES -- High resolution plots:
For 9 pin printers: 72 dpi (horizontally) by 240 dpi
(vertically). For 24 pin printers: 180 dpi
(horizontally) by 360 dpi (vertically).
units [in] specifies the units of length measurement to
be used and is one of the following:
INCHES--Use inches as the unit of measurement.
CENTIMETERS--Use centimeters as the unit of
measurement.
paperWidth [in] specifies the paper width in inches or
centimeters.
plotSpeed [in] specifies the "plotting speed" in inches
(or centimeters) per second. This parameter specifies
the relationship between the plotter horizontal
dimension (in inches or centimeters) and time (in
seconds).
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_Close
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int error;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
25
/*
Program body
:
:
*/
SC_Close();
return 0;
}
SC_PrintChar
============================================================
Low level function to send a character to the printer.
SYNTAX
#include "sc.h"
void SC_PrintChar(char c);
REMARKS
c [in] is the character or command code to send to the
printer attached to the parallel port specified with
the SC_Init function. SC_Init must be called before
using SC_PrintChar.
SC_PrintChar is a low level function; do not use this
function unless you are absolutely sure you know what you
are doing!
SC_PrinterReady
============================================================
Checks if the printer is ready to accept data.
SYNTAX
#include "sc.h"
int SC_PrinterReady(int port);
RETURN VALUE
SC_PrinterReady returns 1 if the printer is ready to
receive data. It returns zero if the printer is not
ready.
26
REMARKS
port [in] specifies the parallel port to which the
printer is attached, and is one of the following:
LPT1--parallel port 1.
LPT2--parallel port 2.
LPT3--parallel port 3.
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int error;
/* Check if printer ready */
if (!SC_PrinterReady(LPT1))
{
printf("Printer not ready!\n");
return 1; /* exit program */
}
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/*
Program body
:
:
*/
SC_Close();
return 0;
}
27
SC_SetErrorTrap
============================================================
Sets up a function to process errors..
SYNTAX
#include "sc.h"
void SC_SetErrorTrap(void (*func)(char *msg));
REMARKS
func [in] is a pointer to a function that is called
when an error occurs in the Strip Chart Library. func
is passed a pointer to an error message string. It is
recommended that your program terminate or
reinitializes itself if an error is detected;
unpredictable results could occur if you continue with
the program.
SEE ALSO
SC_ErrorMsg
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
void ErrorTrapFunc(char *msg)
{ /* user function to trap errors */
printf("%s\n",msg); /* display error message */
exit(1); /* abort program and exit */
}
int main(void)
{
int error;
SC_SetErrorTrap(ErrorTrapFunc);
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
28
/*
Program body
:
:
*/
SC_Close();
return 0;
}
SC_SetHorizontalGrids
============================================================
Specifies the number of horizontal grid lines in Trace
Windows. This function only affects Trace Windows added
after calling this function.
SYNTAX
#include "sc.h"
void SC_SetHorizontalGrids(int divisions, int *error);
REMARKS
divisions [in] is the number of horizontal divisions.
The number of horizontal grid lines drawn is equal to
divisions minus 1.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_AddTraceWindow
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
29
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Set timing (vertical) grids to be 1 second apart. */
SC_SetTimeGrids(1.0, &error);
/* Set Y label format; display at 2.0 second intervals.
*/
SC_SetYlabels(10.0/72.0, "%+0.1f", 2.0, &error);
/* Divide trace into 4 equal sections. */
SC_SetHorizontalGrids(4, &error);
/* Add Trace Window 2.5" from top of paper, 1.0" window
height, amplitude range from -1.0 to 1.0, display
borders, display grids, label Y axis.
*/
traceWindow = SC_AddTraceWindow(2.5, 1.0,
-2.0, 2.0, SCF_BORDER | SCF_GRID | SCF_YLABEL,
&error);
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0;
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
30
SC_SetTimeGrids
============================================================
Specifies the time interval between vertical grid lines
in Trace Windows. This function only affects Trace
Windows added after calling this function.
SYNTAX
#include "sc.h"
void SC_SetTimeGrids(double interval, int *error);
REMARKS
interval [in] is the time interval (in seconds) between
vertical grid lines.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_AddTraceWindow
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Set timing (vertical) grids to be 1 second apart. */
SC_SetTimeGrids(1.0, &error);
/* Set Y label format; display at 2.0 second intervals.
*/
SC_SetYlabels(10.0/72.0, "%+0.1f", 2.0, &error);
/* Divide trace into 4 equal sections. */
SC_SetHorizontalGrids(4, &error);
31
/* Add Trace Window 2.5" from top of paper, 1.0" window
height, amplitude range from -1.0 to 1.0, display
borders, display grids, label Y axis.
*/
traceWindow = SC_AddTraceWindow(2.5, 1.0,
-2.0, 2.0, SCF_BORDER | SCF_GRID | SCF_YLABEL,
&error);
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0;
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
SC_SetTraceRange
============================================================
Changes the minimum and maximum real world coordinates of
a Trace Window. A thick vertical line is automatically
drawn at the current time position to indicate the
change.
SYNTAX
#include "sc.h"
void SC_SetTraceRange(SC_WINDOW *traceWindow,
double ymin, double ymax, int *error);
REMARKS
traceWindow [in] is a pointer to the Trace Window.
ymin [in] is the new real world Y coordinate which
corresponds to the bottom border of the trace window.
ymax [in] is the new real world Y coordinate which
corresponds to the top border of the trace window.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
32
SEE ALSO
SC_AddTraceWindow
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Set timing (vertical) grids to be 1 second apart. */
SC_SetTimeGrids(1.0, &error);
/* Set Y label format; display at 2.0 second intervals.
*/
SC_SetYlabels(10.0/72.0, "%+0.1f", 2.0, &error);
/* Divide trace into 4 equal sections. */
SC_SetHorizontalGrids(4, &error);
/* Add Trace Window 4" from top of paper,
1" window height, amplitude range is initially from -2.0
to 2.0, display borders, display grids, label Y axis.
*/
traceWindow = SC_AddTraceWindow(4.0, 1.0, -2.0, 2.0,
SCF_BORDER | SCF_GRID | SCF_YLABEL, &error);
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0; /* triangle wave */
SC_Draw();
SC_Advance(1.0); /* one second steps */
/* Change the window amplitude range to -4.0 to 4.0 at
time = 5.0 seconds.
33
*/
if (i == 5)
SC_SetTraceRange(traceWindow, -4.0, 4.0, &error);
}
SC_Close();
return 0;
}
SC_SetYlabels
============================================================
Specifies the label format of the vertical axis in Trace
Windows. This function only affects Trace Windows added
after calling this function.
SYNTAX
#include "sc.h"
void SC_SetYlabels(double charHeight, char *format,
double interval, int *error);
REMARKS
charHeight [in] is the character height (in inches or
centimeters).
format [in] is a C printf format string to be used for
the vertical axis labels. Use floating point
specifiers in the format string, for example: "%9.3f"
or "%+10.4e". To display labels as integers, use
"%-1.0f".
interval [in] is the time interval (in seconds) between
displaying the labels.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_AddTraceWindow
34
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Set timing (vertical) grids to be 1 second apart. */
SC_SetTimeGrids(1.0, &error);
/* Set Y label format; 10 point character height;
display at 2.0 second intervals. */
SC_SetYlabels(10.0/72.0, "%+0.1f", 2.0, &error);
/* Divide trace into 4 equal sections. */
SC_SetHorizontalGrids(4, &error);
/* Add Trace Window 2.5" from top of paper,
1.0" window height, amplitude range from -1.0 to 1.0,
display borders, display grids, label Y axis.
*/
traceWindow = SC_AddTraceWindow(2.5, 1.0,
-2.0, 2.0, SCF_BORDER | SCF_GRID | SCF_YLABEL,
&error);
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0;
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
35
SC_Text
============================================================
Displays a text string in a Text Window.
SYNTAX
#include "sc.h"
void SC_Text(SC_WINDOW *textWindow, char *string,
int *error);
REMARKS
textWindow [in] is a pointer to the Text Window in
which to display the string.
string [in] is the ASCII text string to display.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
Calling SC_Text for a Text Window that has not yet
finished printing the string from a previous call to
SC_Text will cause the two strings to be printed over
each other.
SEE ALSO
SC_AddTextWindow
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
SC_WINDOW *textWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
if (error)
{
printf("%s\n",SC_ErrorMsg(error));
return 1; /* exit */
}
36
/* Add Text Window 1.5" from top of paper,
0.25" window height
*/
textWindow = SC_AddTextWindow(1.5, 0.25, &error);
/* Draw */
for (i=0; i < 10; i++) /* 10 second plot */
{
/* Display "hello world" every 2 seconds */
if ((i%2) == 0)
SC_Text(textWindow,"Hello World!",&error);
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
SC_Title
============================================================
Specifies the title string for a Title Window.
SYNTAX
#include "sc.h"
void SC_Title(SC_WINDOW *titleWindow, char *titleString,
int *error);
REMARKS
titleWindow [in] is a pointer to the Title Window in
which to display the string.
titleString [in] is a pointer to a text string.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
SEE ALSO
SC_AddTitleWindow
37
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
SC_WINDOW *titleWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Title Window 5.5" from top of paper,
0.25" window height, display every 2.0 seconds
*/
titleWindow = SC_AddTitleWindow(5.5, 0.25, 2.0, &error);
/* Set title string. */
SC_Title(titleWindow, "Hello World!", &error);
/* Draw */
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
38
SC_Trace
============================================================
Sets the current trace amplitude in a Trace Window.
SYNTAX
#include "sc.h"
void SC_Trace(SC_WINDOW *traceWindow, double y,
int *error);
REMARKS
traceWindow [in] is a pointer to the Trace Window.
y [in] is the current trace amplitude in the same real
world units as the window limits, ymin and ymax,
specified in the SC_AddTraceWindow function. When you
call SC_Draw, a line will be drawn between the last two
points in the Trace Window set by the last two calls to
SC_Trace.
error [out] is a pointer to an error code. A non-zero
error code indicates an error condition.
Gaps may appear in the trace plot if SC_Trace is called
twice for the same Trace Window without an intervening
call to SC_Draw.
SEE ALSO
SC_AddTraceWindow, SC_SetTraceRange
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
double y;
SC_WINDOW *traceWindow;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
39
/* Set timing (vertical) grids to be 1 second apart. */
SC_SetTimeGrids(1.0, &error);
/* Set Y label format; display at 2.0 second intervals.
*/
SC_SetYlabels(10.0/72.0, "%+0.1f", 2.0, &error);
/* Divide trace into 4 equal sections. */
SC_SetHorizontalGrids(4, &error);
/* Add Trace Window 2.5" from top of paper,
1.0" window height, amplitude range from -1.0 to 1.0,
display borders, display grids, label Y axis.
*/
traceWindow = SC_AddTraceWindow(2.5, 1.0,
-2.0, 2.0, SCF_BORDER | SCF_GRID | SCF_YLABEL,
&error);
/* Draw a triangle wave of amplitude 2.0 */
y = 2.0;
for (i=0; i < 10; i++) /* 10 second plot */
{
SC_Trace(traceWindow, y, &error);
y = y * -1.0;
SC_Draw();
SC_Advance(1.0); /* one second steps */
}
SC_Close();
return 0;
}
SC_yoffset
============================================================
Global variable which keeps track of the page offset of
the bottom border of the last window added.
SYNTAX
#include "sc.h"
extern double SC_yoffset;
REMARKS
SC_yoffset provides an easy way to add windows
sequentially to the strip chart. Initially, SC_yoffset
is set to zero (the top of the page). When you add a
window, SC_yoffset is set to the bottom of the window,
that is, SC_yoffset is set to yoffset + yheight, where
40
yoffset is the window offset from the top of the page and
yheight is the window height.
EXAMPLE
#include <stdio.h>
#include <stdlib.h>
#include "sc.h"
int main(void)
{
int i;
int error;
SC_WINDOW *titleWindow;
SC_WINDOW *traceWindow1, *traceWindow2, *traceWindow3;
/* Initialize: 8.5 inch wide paper,
plot speed = 1 inch/second */
SC_Init(LPT1, SC_24PIN, SC_LOW_RES, INCHES, 8.5, 1.0,
&error);
/* Add Title Window 0.5" from top of paper,
0.25" window height, display every 2.0 seconds
*/
titleWindow = SC_AddTitleWindow(SC_yoffset+0.5, 0.25,
2.0, &error);
/* Add three trace windows, each 1.0" high with 0.25"
spacing between windows */
traceWindow1 = SC_AddTraceWindow(SC_yoffset+0.25, 1.0,
-2.0, 2.0, SCF_NO_FLAGS, &error);
traceWindow2 = SC_AddTraceWindow(SC_yoffset+0.25, 1.0,
-2.0, 2.0, SCF_NO_FLAGS, &error);
traceWindow3 = SC_AddTraceWindow(SC_yoffset+0.25, 1.0,
-2.0, 2.0, SCF_NO_FLAGS, &error);
/*
Program Body
:
:
*/
SC_Close();
return 0;
}
41
C H A P T E R 4
Error Messages
This chapter lists the error messages returned by function
SC_ErrorMsg.
Out of memory
The system has run out of memory. Try using the large
memory model for your compiler.
Incorrect window type for this function
You passed a pointer (SC_WINDOW *) to a window that is
inappropriate for this function. For example, function
SC_Text accepts only pointers to Text Windows; passing a
Trace Window pointer to SC_Text will generate this error.
YMIN equals YMAX
You passed the same numerical value for arguments ymin
and ymax to functions SC_AddTraceWindow and
SC_SetTraceRange.
Window offset must be greater than zero
The value of argument yoffset must be greater than zero
when calling functions SC_Add???Window.
Window height must be greater than zero
The value of argument yheight must be greater than zero
when calling functions SC_Add???Window.
Invalid printer type/resolution
You passed invalid values for arguments printerType
and/or plotResolution to function SC_Init.
Time interval must be greater than zero
You passed a time interval argument that is less than or
equal to zero. All time interval arguments must be
greater than zero.
Number of divisions must be greater than zero
You passed a number of horizontal or vertical grid
divisions argument that is less than or equal to zero.
The number of horizontal or vertical grid divisions must
be greater than zero.
String is a null pointer
You passed a NULL pointer for a string argument. Use an
empty string ("") to pass a null string.
42
Character height must be greater than zero
The value of argument charHeight must be greater than
zero in function SC_SetYlabels.
43
